#nullable enable

using Application.Core.Dto;

namespace Application.Service.Users;

/// <summary>
/// 用户服务接口
/// <para>功能：定义用户管理服务的核心功能接口</para>
/// </summary>
public interface IUserService
{
    /// <summary>
    /// 查询系统中所有注册用户的信息
    /// </summary>
    /// <returns>返回包含所有用户基本信息的集合</returns>
    Task<IEnumerable<UserDto>> GetAllAsync();

    /// <summary>
    /// 获取所有用户实体（内部使用）
    /// </summary>
    /// <returns></returns>
    Task<IEnumerable<User>> GetAllEntiyAsync();

    /// <summary>
    /// 通过用户ID精确查询特定用户的详细信息
    /// </summary>
    /// <param name="userId">用户id</param>
    /// <returns>返回指定用户的完整信息或null（用户不存在）</returns>
    Task<UserDto?> GetAsync(int userId);

    /// <summary>
    /// 通过用户名精确查询特定用户的详细信息
    /// </summary>
    /// <param name="username">用户名</param>
    /// <returns>返回指定用户的完整信息或null（用户不存在）</returns>
    Task<UserDto?> GetAsync(string username);

    /// <summary>
    /// 创建新的用户账户
    /// </summary>
    /// <param name="dto">用户创建信息</param>
    /// <returns>返回创建结果、错误信息和创建的用户信息元组</returns>
    Task<(bool ok, string? error, UserDto? user)> CreateAsync(UserCreateDto dto);

    /// <summary>
    /// 更新指定用户的基本信息和状态
    /// </summary>
    /// <param name="userId">用户ID</param>
    /// <param name="dto">用户更新信息</param>
    /// <returns>返回更新结果、错误信息和更新后的用户信息元组</returns>
    Task<(bool ok, string? error, UserDto? user)> UpdateAsync(int userId, UserUpdateDto dto);

    /// <summary>
    /// 永久删除指定用户及其相关数据
    /// </summary>
    /// <param name="userId">用户id</param>
    /// <returns>返回删除结果和错误信息结果元组（超级管理员不可删除）</returns>
    Task<(bool ok, string? error)> DeleteAsync(int userId);

    /// <summary>
    /// 查询指定用户当前拥有的所有权限
    /// </summary>
    /// <param name="userId">用户Id</param>
    /// <returns>返回用户权限查询结果和权限列表结果元组</returns>
    Task<(bool ok, string? error, IEnumerable<Permission> perms)> GetPermissionsAsync(int userId);

    /// <summary>
    /// 为指定用户批量设置权限列表
    /// </summary>
    /// <param name="userId">用户Id</param>
    /// <param name="permissionIds">用户权限列表</param>
    /// <returns>返回权限设置结果和错误信息结果元组</returns>
    Task<(bool ok, string? error)> SetPermissionsAsync(int userId, List<int> permissionIds);
    
    /// <summary>
    /// 为指定用户添加单个权限
    /// </summary>
    /// <param name="userId">用户Id</param>
    /// <param name="permissionId">待增加权限</param>
    /// <returns>返回权限添加结果和错误信息结果元组</returns>
    Task<(bool ok, string? error)> AddPermissionAsync(int userId, int permissionId);
    
    /// <summary>
    /// 从指定用户移除单个权限
    /// </summary>
    /// <param name="userId">用户Id</param>
    /// <param name="permissionId">权限Id</param>
    /// <returns>返回权限删除结果和错误信息结果元组</returns>
    Task<(bool ok, string? error)> RemovePermissionAsync(int userId, int permissionId);
}